home *** CD-ROM | disk | FTP | other *** search
/ STraTOS 1997 April & May / STraTOS 1 - 1997 April & May.iso / CD01 / INTERNET / SITES / RAND / QLEM.TXT < prev    next >
Encoding:
Text File  |  1997-02-06  |  13.2 KB  |  293 lines
  1. QLem 1.45Jx(beta) manual
  2. ========================
  3.  
  4. This is a short description of my QL emulator for the various Atari ST
  5. machines and the Falcon030. It _may_ also run on the TT.
  6.  
  7. Please, do not make this version of the emulator available to anyone else
  8. without asking me first. The emulator works rather well, but I want some
  9. more feed-back before I do a general release.
  10. If you have anything at all to say regarding QLem, _please_ contact me.
  11.  
  12. All questions, suggestions, help offers, bug reports etc are very welcome.
  13. If you want to help develop this emulator further, I'd really appreciate it.
  14. I don't have as much time to spend on my programming projects nowadays as I
  15. used to have.  :-(
  16.  
  17. Johan Klockars, 960120
  18. (rand@cd.chalmers.se  or  johan@rand.thn.htu.se)
  19.  
  20.  
  21. Overview of features and handling
  22. =================================
  23.  
  24. A QDOS JS rom dump is included in the emulator archive since I've heard from
  25. a number of sources that Amstrad is not interested in the issue.
  26.  
  27.  
  28. How to start the QDOS emulator
  29. ------------------------------
  30. Run QDOSJX.PRG with QDOS.JS (and TRUMP.121 if available) in the current
  31. directory. A text with some information about the emulator will be shown
  32. while the emulator loads and patches the rom dumps.
  33. After a while the screen will clear and finally the familiar F1/F2 screen
  34. will appear. If you run QLem on a monochrome screen, you'll not be able to 
  35. read the text without pressing HELP once. This is caused by the way the
  36. screen emulation converts from the QL four colour mode to black and white.
  37.  
  38.  
  39. What's known to work in this version of the emulator
  40. ---------------------------------------------------
  41. (Apart from the obvious things that is.)
  42. - JS rom dumps
  43. - Screen emulation on monochrome and colour monitors
  44. - TOS/DOS floppy support (root directory only)
  45. - With TrumpCard 1.21 rom dump, read and write(no error checks) of QL disks
  46. - Boot from flp1_boot(QL disk with TrumpCard 1.21)
  47.  
  48.  
  49. What _should_ work, but hasn't been tested since '92
  50. ----------------------------------------------------
  51. - JM rom dumps
  52. - Parallel port (PAR)
  53. - Second disk drive
  54. - Joystick emulation (arrow keys)
  55. - Changeable delay for games (see DELAY below)
  56. - Boot from dsk1_boot (TOS/DOS disk)
  57.  
  58.  
  59. Available support programs
  60. --------------------------
  61. A GEM based file transfer program QL -> TOS/DOS with formatting of QL disks
  62. is available. It _should_ work with HD disks, but I have no such QL disks...
  63. If anyone has any info on the new QL filesystems (level 2?), please let
  64. me know.
  65.  
  66. A native ST monochrome mode screen device driver (no graphics) is supplied
  67. in the emulator archive. To run it, use the following (or similar):
  68.   a=malloc(20000):lbytes "dsk1_textdev.cde":call a
  69. The device driver is called dsp_ and should be able to handle everything that
  70. the normal con_ driver can (except graphics), but it's _much_ faster (fastest
  71. text draw routines I've ever seen on an ST) and can only be used with the
  72. screen emulator turned off (otherwise the output is immediately overwritten).
  73.  
  74.  
  75. The keyboard
  76. ------------
  77. The keyboard layout currently depends on both the QL rom used and the
  78. keyboard your ST has. I hope to fix this in the near future.
  79.  
  80. Keys            Description
  81.  
  82. F6 - F10        The function keys F6-F10 are the same as F1-F5 but shifted, as
  83.                 on other extension keyboards for the QL.
  84.                 However, they have no KEYROW codes.
  85.  
  86. Help            Monochrome:
  87.                   Used to switch between the two colour emulation modes.
  88.                   There are two modes because the monochrome emulation can only
  89.                   show two of the four possible colours at once.
  90.                   MODE 8 is emulated in exactly the same way as MODE 4, which
  91.                   makes it look somewhat funny at times.
  92.                 Colour:
  93.                   Used to switch between emulation for MODE 4, MODE 8 and
  94.                   MODE 8 with flash. The MODE 4 emulation is by far the
  95.                   fastest and can (should) be used all the time.
  96.  
  97. Ctrl-Alt-Help   Tries to reset the QL emulator. This does not always work.
  98.  
  99. Ctrl-Alt-Delete Hard reset (return to ST mode).
  100.  
  101. Delete          Same as Ctrl - left.
  102.  
  103. Backspace       Same as Ctrl - right.
  104.  
  105. UNDO            Equivalent to the ctrl-F5 combination, ie it stops output to
  106.                 the screen temporarily, until another key is pressed.
  107.  
  108. * (numeric)     Toggles the screen emulators modes:
  109.                 multitasking  -  default mode, does not work for all programs
  110.                                  The priority can be changed in the the usual
  111.                                  ways if needed.
  112.                 interrupt     -  emulates the screen no matter what...
  113.                                  Some games and other special programs need
  114.                                  this mode. Also gives less 'jumpiness' in
  115.                                  the display.
  116.                 none          -  no emulation of the screen is done
  117.                                  For extra speed or testing of native screen
  118.                                  device drivers such as textdsp.cde.
  119.                 
  120. +- (numeric)   Only on colour monitor.
  121.                 Switch between showing the top and the bottom of the screen
  122.                 (the whole screen won't fit).
  123.  
  124. The rest of the keys have their normal meaning.
  125. None of the special keys have any KEYROW codes.
  126.  
  127.  
  128. New SuperBASIC commands/functions
  129. ---------------------------------
  130.       SHOWFIX   -   Shows what fixes the emulator has been forced to do
  131.       RCONV     -   Removes the screen emulation job (not the interrupt one)
  132.       SCONV     -   Starts the screen emulation job again
  133.       MALLOC    -   Reserves memory on the common heap (addr=malloc(n))
  134.       FREE      -   Frees memory reserved on the common heap (free addr)
  135.       DELAY     -   Sets the delay used in the KEYROW code (delay word)
  136.                     (A DBRA counter is set to the value you give, which will
  137.                      cause a delay of about 12*word cycles per KEYROW read)
  138.       HEADREAD  -   Reads a file header.
  139.       HEADSET   -   Sets a file header.
  140.       FLOPPY    -   Informs the TOS/DOS floppy device driver that there's
  141.                     a file name translation table to use. See below.
  142.  
  143.  
  144. TOS/DOS floppy support
  145. ----------------------
  146. The only disk drive support built into QLem is a TOS/DOS directory
  147. device driver. This usually works rather well (together with QL2ST for
  148. transfers from QL disks), but there are a few things that can cause
  149. problems:
  150. - The file names are the normal TOS/DOS 8+3 characters.
  151.   The native QL file system handles file names of up to 36 characters.
  152. - Normal QL disks have extra information for each file, for example the
  153.   size of the data area for EXEC(utable) programs. TOS can't write that.
  154. - There's currently no error checking on either read or write.
  155.   Most of the time everything will work fine, though...
  156.  
  157. The latest versions of QLem/QL2ST partially solves the first problem by
  158. introducing 'name translation tables' and has a work around for the second.
  159.  
  160. Name translation tables
  161. -----------------------
  162. The idea is that QL2ST writes all the file information from a QL floppy
  163. into a special file (_QDOS.NME) on the TOS file system. The TOS/DOS
  164. disk device driver under QLem can then be made to use this information in
  165. the following way:
  166.  
  167.   a=malloc(1000)                 Size depends on the _QDOS.NME size
  168.   lbytes "dsk1__qdos.nme",a
  169.   print floppy(a)                The value printed is of no importance
  170.  
  171. After that, every time you try to open a file, the name translation
  172. table will be searched for a match. When one is found, the correct
  173. TOS/DOS file name will replaced the name you gave before the actual
  174. open operatioyn takes place.
  175.  
  176. As an example, imagine that you have a QL floppy with a lot of files.
  177. Using QL2ST, select them all and start the conversion.
  178. For each file, QL2ST will ask you for a new file name, while suggesting
  179. one based on the QL file name. After the file is written, the _QDOS.NME
  180. file, in the same directory, will be updated (perhaps created as well)
  181. with both the original name/data and your TOS file name.
  182. When you want to use the disk with the converted files under QLem,
  183. do the SuperBASIC steps described above.
  184.  
  185. If you for example converted a file named my_database_dat using QL2ST,
  186. the suggested name would've been MY_DATAB.DAT. A directory of the TOS
  187. disk under QLem will also show that name. However, if you want to open
  188. the file, from within Archive or anywhere else, you can use _either_
  189. name without problems.
  190.  
  191. The name translation table will automatically be invalidated if you
  192. change disks.
  193.  
  194.  
  195. Additional file information on TOS disks
  196. ----------------------------------------
  197. It appears there us actually space in the directory entries on TOS disks
  198. for at least the most important of the QL file information. As was
  199. mentioned before, that information can't be written by TOS, though.
  200.  
  201. The important extra information is that about the file type and data area,
  202. which is needed for EXEC(ing) of files to work.
  203. When files are saved to a TOS/DOS disk from under QLem, that information
  204. will be written, so if it was just available in the first place everything
  205. could be corrected. Actually, the device driver will supply some default
  206. values for the information if none is available. That was the case with
  207. older versions of QLem as well, but other errors caused direct EXEC from
  208. floppy to fail anyway (you could always copy to a RAM disk and EXEC there).
  209.  
  210. Now, with the name translation tables, things can be corrected.
  211. While it might sound reasonable to use the information from in there
  212. directly, that would be very dangerous when updates are done to files on
  213. the disk (the table wouldn't change), so a simple program is used instead.
  214. Run the supplied SuperBASIC program, FIXFILES, and follow the instructions.
  215. (LRUN dsk1_fixfiles should do the trick.)
  216.  
  217.  
  218. Automatic file loading at startup
  219. ---------------------------------
  220. To make it possible to try QLem even on systems without working disk
  221. access, for example under STonX, a simple scheme has been implemented
  222. to allow files to be loaded into memory when QLem is started.
  223. QLem will look for a file called 'LOADFILE.DAT', load all files mentioned
  224. in it and put them at the specified memory locations.
  225. A short example:
  226.  
  227. $200000
  228. j:\qlprogs\qmon2
  229. $210000
  230. j:\qlem.140\qlem_140.txt
  231. $0
  232.  
  233. All addresses must be given in hexadecimal form, with a leading '$'.
  234. The number '$0' marks the end of the file.
  235. QLem will abort if it can't find all the files mentioned, but it will
  236. not check whether it is possible to store them at the specified addresses. 
  237. Space for the files will be allocated using Malloc at first. Later the
  238. files are moved up to the top of RAM and finally, just before QDOS is
  239. started, the files are moved to the specified locations.
  240.  
  241.  
  242. Additional comments
  243. -------------------
  244. - Most programs should work under the emulator, for example:
  245.     Turbo, Desktop Publisher, The Editor, PSION Xchange and Scrabble
  246. - All keys may not give the expected characters.
  247. - There is no timeout on disk operations.
  248. - Use of unsupported devices can lock up the emulator.
  249. - If you have another rom version that you would like to use, then send me a
  250.   copy and I will look into it. This especially applies to disk interfaces.
  251. - The emulator is set to give a 1Mb QL since I only had that amount of memory
  252.   when I last did any work on it. There should be no problem changing this to
  253.   2Mb, but more will give serious problems due to 16 bit slave block addressing
  254.   in QDOS. I'll fix it when I have the time.
  255. - It would be nice to have a list of compatible and non-compatible programs,
  256.   so please let me know what you've tried.
  257. - If a program crashes for you, I can most likely fix it quite easily if you
  258.   mail me an executable copy.
  259.  
  260.  
  261. For programmers
  262. ---------------
  263. Some programs have trouble with the way the ST protects low memory.
  264. If you know a bit about machine code programming, you can use a monitor
  265. program, for example Qmon, to help find out what's wrong.
  266. The problems will show up as an illegal instruction error in the m/c-monitor.
  267. This is because the emulator has to trap all accesses to low memory, mainly
  268. because of the vectored QDOS routines ($c0-$12a). If the error trapping code
  269. does not recognize the offending instructions it will execute an ILLEGAL
  270. instruction to enter the monitor program.
  271.  
  272. For the Falcon030 some new code had to be written, dealing with the
  273. different exception stack format, MMU page tables, cache control etc.
  274. It all seems to work well now, but if you have trouble understanding
  275. something (there are no QL debuggers that handle the '030 instructions
  276. that I know of)), please don't hesitate to contact me.
  277.  
  278. If you need help, please email.
  279.  
  280. What still needs to be done (in no particular order):
  281. - RS-232/MIDI device drivers
  282. - 'Virtual' micro-drives
  283. - Native ST colour screen device driver
  284. - Graphics support in the native monochrome device driver
  285. - Fixes to the hard disk code. It's currently not enabled in the emulator
  286. - Support for better graphics modes on TT/Falcon/graphic-cards
  287. - Falcon DSP support for screen emulation. Yes, yes, yes!
  288. - Sound
  289.  
  290. And probably a lot of other things I haven't thought of. Let me know!
  291.  
  292. Johan Klockars
  293.